home *** CD-ROM | disk | FTP | other *** search
/ QRZ! Ham Radio 6 / QRZ Ham Radio Callsign Database - Volume 6.iso / pc / files / t_nansi / nan24hyc.arc / nansi.doc < prev    next >
Text File  |  1990-10-31  |  12KB  |  274 lines
  1.           nansi - Enhanced MS-DOS ansi console driver
  2.  
  3. SYNOPSIS
  4.     Include in \config.sys the line
  5.         device=nansi.sys
  6.  
  7. DESCRIPTION
  8.     Nansi.sys is a console driver which understands ANSI control sequences.
  9.     It has several advantages over ANSI.SYS (the driver supplied with DOS):
  10.     1. It supports new escape sequences (see below).
  11.     2. It provides MUCH faster output under certain conditions.
  12.     3. It supports EGA 43-line mode and ATT 6300 50-line mode.
  13.     4. The darned bell is now 1/4 second instead of 1/2 second long.
  14.  
  15.     What a console driver does:
  16.     When you, for example, type
  17.         C:> type foo.txt
  18.     COMMAND.COM opens the file foo.txt, reads it, and writes it to
  19.     the console driver, which puts it up on the screen.
  20.  
  21.     Both ansi.sys and nansi.sys use IBM Video BIOS to control the screen.
  22.     However, nansi.sys bypasses BIOS if the screen is in a text mode; this
  23.     allows much faster operation under certain conditions.
  24.  
  25.     While putting text up on the screen, (n)ansi.sys keeps a lookout for
  26.     the escape character (chr(27), known as ESC); this character signals
  27.     the start of a terminal control sequence.
  28.     Terminal control sequences follow the format
  29.         ESC [ param; param; ...; param cmd
  30.     where
  31.         ESC    is the escape character chr$(27).
  32.         [    is the left bracket character.
  33.         param    is an ASCII decimal number, or a string in quotes.
  34.         cmd    is a case-specific letter identifying the command.
  35.     Usually, zero, one, or two parameters are given.  If parameters
  36.     are omitted, they usually default to 1; however, some commands
  37.     (KKR and DKOCT) treat the no-parameter case specially.
  38.     Spaces are not allowed between parameters.
  39.  
  40.     For example, both ESC[1;1H and ESC[H send the cursor to the home
  41.     position (1,1), which is the upper left.
  42.  
  43.     Either single or double quotes may be used to quote a string.
  44.     Each character inside a quoted string is equivalent to one numeric
  45.     parameter.  Quoted strings are normally used only for the Keyboard
  46.     Key Reassignment command.
  47.  
  48. Control Sequences
  49.     The following table lists the sequences understood by nansi.sys.
  50.     Differences between nansi.sys and the standard ansi.sys are marked
  51.     with a vertical bar (|).
  52.  
  53. Cursor Positioning
  54. Short    Long name        Format        Notes
  55. CUP    cursor position        ESC[y;xH    Sets cursor position.
  56. HVP    cursor position        ESC[y;xf    Same as CUP; not recommended.
  57. CUU    cursor up        ESC[nA        n = # of lines to move
  58. CUD    cursor down        ESC[nB
  59. CUF    cursor forward        ESC[nC        n = # of columns to move
  60. CUB    cursor backward        ESC[nD
  61. DSR    Device Status, Report!    ESC[6n        Find out cursor position.
  62. CPR    Cursor Position report    ESC[y;xR<CR>    Response to DSR, as if typed.
  63. SCP    Save Cursor Position    ESC[s        Not nestable.
  64. RCP    Restore Cursor Position ESC[u
  65.  
  66. Editing
  67. ED  |    Erase in Display    ESC[0J or ESC[J    Clear to end of screen.
  68.     |                ESC[1J    Clear to start of screen.
  69.                 ESC[2J    Clears screen.
  70. EL    Erase in Line        ESC[K    Clears to end of line.
  71. IL  |    Insert Lines        ESC[nL    Inserts n blank lines at cursor line.
  72. DL  |    Delete Lines        ESC[nM    Deletes n lines, including cursor line.
  73. ICH |    Insert Characters    ESC[n@    Inserts n blank chars at cursor.
  74. DCH |    Delete Characters    ESC[nP    Deletes n chars, including cursor char.
  75.  
  76.  
  77. Mode-Setting
  78. SGR    Set Graphics Rendition    ESC[n;n;...nm    See character attribute table.
  79. SM    Set Mode        ESC[=nh        See screen mode table.
  80. RM    Reset Mode        ESC[=nl        See screen mode table.
  81. IBMKKR    Keyboard Key Reass.    ESC["string"p
  82.     The first char of the string gives the key to redefine; the rest
  83.     of the string is the key's new value.
  84.     To specify unprintable chars, give the ASCII value of the char
  85.     outside of quotes, as a normal parameter.
  86.     IBM function keys are two byte strings; see the IBM Basic manual.
  87.     For instance, ESC[0;";dir a:";13;p redefines function key 1 to
  88.     have the value "dir a:" followed by the ENTER key.
  89.       | If no parameters given, all keys are reset to their default values.
  90.  
  91. DKOCT | Output char translate    ESC[n;ny
  92.       | When first char is encountered in output request, it is replaced with
  93.       | the second char.  This might be useful for previewing text before
  94.       | sending it to a printer with a funny print wheel.
  95.       | If no parameters are given, all chars are reset to normal.
  96.  
  97.  
  98. Character Attributes
  99.     The Set Graphics Rendition command is used to select foreground
  100.     and background colors or attributes.
  101.     When you use multiple parameters, they are executed in sequence, and
  102.     the effects are cumulative.
  103.        Attrib code        Value
  104.         0        All attributes off (normal white on black)
  105.         1        Bold
  106.         4        Underline
  107.         5        Blink
  108.         7        Reverse Video
  109.         8        Invisible (but why?)
  110.         30-37        foregnd blk/red/grn/yel/blu/magenta/cyan/white
  111.         40-47        background (no effect in graphics modes)
  112.  
  113. Screen Modes
  114.     The Set Mode and Reset Mode sequences both accept one parameter,
  115.     with the following values:
  116.         Mode Code    Value (same for Set and for Reset)
  117.         0    text 40x25 Black & White
  118.         1    text 40x25 Color
  119.         2    text 80x25 Black & White
  120.         3    text 80x25 Color
  121.         4    bitmap 320x200 4 bits/pixel
  122.         5    bitmap 320x200 1 bit/pixel
  123.         6    bitmap 640x200 1 bit/pixel
  124.           | 13    EGA graphics 320x200 4 bits/pixel
  125.           | 14    EGA graphics 640x200 4 bits/pixel
  126.           | 15    EGA [ IBM Monochrome display 640x350 2 bits/pixel?]
  127.           | 16    EGA graphics 640x350 4 bits/pixel [with full 256K]
  128.  
  129.         Mode Code    Set            Reset
  130.         7      *Wrap at end of line    No wrap at EOL
  131.           | 43    43 Lines on EGA           *25 Lines
  132.           | 44    Wait for retrace       *No wait
  133.           | 45     *Graphics Cursor        No simulated graphics cursor
  134.           | 50    50 Lines on ATT 6300   *25 Lines
  135.  
  136.         [ * = default ]
  137.  
  138. Screen Snow
  139.     If your screen flares up with annoying little white bars ("snow"),
  140.     you probably should tell Nansi to wait for retrace before writing
  141.     to the screen, by sending the string
  142.         ESC [ = 44 h
  143.     This doesn't clear up the snow under all conditions, but it helps
  144.     quite a bit.  Unfortunately, it also slows down output somewhat.
  145.  
  146. Little Dead Blobs
  147.     If you are using a graphics mode, and the cursor leaves little
  148.     dead blobs behind when it moves, you are probably using a program
  149.     which bypasses DOS (naughty, naughty).    It might help to tell
  150.     Nansi to turn off its graphics cursor by sending the string
  151.         ESC [ = 45 l
  152.     (The last character in that string is a lowercase "L".)
  153.  
  154. Faster Output
  155.     Any program that
  156.     1) uses Nansi.sys,
  157.     2) sets the console to RAW mode (with IOCTL), and
  158.     3) buffers its output (C programmers: use setbuf),
  159.     can achieve EXTREMELY high screen update speeds in return
  160.     for giving up the special functions of the keys ^C, ^S, and ^P
  161.     (which many programs, editors for example, don't want anyway).
  162.     See IOCTL in the MS-DOS 3.x Technical Reference for more info.
  163.  
  164. Portability to Microsoft Windows
  165.     According to Microsoft, any program that uses ANSI.SYS escape
  166.     sequences will work under Microsoft Windows without changes.
  167.     It appears that the speed advantages of Nansi may be preserved
  168.     by MS-Windows when better graphics boards become available.
  169.     This is one of the best reasons for using Nansi instead of
  170.     directly accessing the memory mapped video text buffer.
  171.  
  172.     [ Caveat: I have found that Cursor Position Report simply
  173.       does not work under MS-Windows.  This is a shame, because
  174.       CPR makes it possible for text editors to automatically sense
  175.       the size of the screen. ]
  176.  
  177. EXAMPLES
  178.     See the files setraw.* for Macro Assembler, Lattice C,
  179.     and Microsoft C routines for entering and leaving raw mode.
  180.  
  181.     The files mode*.txt included with nansi.sys in the library
  182.     new_ansi.lbr contain the Set Mode sequences to set various
  183.     screen modes; for instance, to try out 43 line mode, type
  184.         C:> type MODE43.TXT
  185.     [ To get back to normality, type the file "mode3.txt"; don't use
  186.       the mode command, as that doesn't let nansi know what happened...]
  187.  
  188.     The programs view.com and more.com are demos of this driver's
  189.     blinding screen update speed; refer to view.doc and more.doc for
  190.     details.  Briefly, typing
  191.         C:> more foo.txt
  192.     shows you the file foo.txt, pausing every 24 lines for you to hit
  193.     the spacebar.  Typing
  194.         C:> view foo.txt
  195.     shows you the first page of the file foo.txt; typing PgUp or PgDn moves
  196.     you backwards or forwards in the file; typing 'q' exits to DOS.
  197.  
  198.  
  199. BUGS
  200.     The Set Mode and Reset Mode codes 43, 44, 45, and 50 were chosen
  201.     without even looking to see if there are established codes
  202.     for those functions.
  203.  
  204.     Insert and delete character do not work in graphics modes
  205.     because BIOS does not include a scroll left/right function.
  206.  
  207.     Graphics mode writing is slow because it uses BIOS.
  208.  
  209.     It is difficult to add new screen access methods to nansi.asm;
  210.     nansi should be rewritten so parsing text into printable
  211.     blocks is separate from writing those blocks onto the screen.
  212.  
  213.     Does not support some other useful functions.
  214.  
  215.     Cursor Position Report has a carriage return in it, which is what
  216.     ansi.sys does, but is nonstandard.
  217.  
  218.     When using 43 line mode, typing MODE CO80 will get you back
  219.     to 25 line mode- but NANSI will still scroll as if there were 43
  220.     lines!    You have to use the SET MODE escape sequence instead of MODE.
  221.     Should either intercept BIOS calls or sense the extended AT/EGA bios
  222.     variable for # of lines.
  223.  
  224. Version
  225.     This is a modification of NANSI 2.4, incorporating changes made
  226.     by Ron Henderson <crh@hpcvmcrh.cv.hp.com> to version 2.2. These
  227.     changes (non-destructive tab, ignore NULLs instead of outputing
  228.     as spaces, send "nansi" in response to ESC[c query, clear with
  229.     ESC [ J, ESC [ 0 J, ESC [ 1 J) were merged into NANSI 2.4 by
  230.     Howard Chu <hyc@admin.lsa.umich.edu>, Oct. 30, 1990. This doc
  231.     file has been updated to represent the current state.
  232.     (The version number can be found by typing TYPE NANSI.SYS.)
  233.     This version, 2.4, created August 1986.
  234.     It fixes several nasty bugs in the last release (2.2), so please
  235.     pass this version on to anyone who had the old version.
  236.  
  237. NOTE
  238.     I intend to upgrade this program from time to time, and will
  239.     post new versions to Usenet.
  240.     Problems or suggestions should be sent to the author, Daniel Kegel:
  241.     Post:    17 Mulberry Street
  242.         Rochester, NY 14620 USA
  243.     Usenet: ...rochester!srs!dan
  244.  
  245.     My thanks to Ed Nather, Pete Galvin, Bill Dudley, and others
  246.     who have helped fix bugs or who have contributed features.
  247.  
  248.     This program and all files associated with it are hereby placed
  249.     in the public domain, and thus may be freely copied and distributed.
  250.  
  251.     If you really like this program, either
  252.     (a) improve it, and place your improvements in the public domain,
  253.     (b) write a neat program which uses Nansi's unique speed, and
  254.         place your program in the public domain,
  255.     (c) tip the author (Tip; contraction for "To Inspire Programmer";
  256.         traditionally, a contribution of $5 per copy), or
  257.     (d) resolve to become a better human being in the future.
  258.  
  259.     However, I suggest that any modifications be clearly marked, and
  260.     (if reasonable) surrounded by IF/ ELSE/ ENDIF statements.
  261.     The programmer doing the modification should append his/her initials
  262.     to the version number string (near the device driver header).
  263.  
  264. FILES
  265.     makefile
  266.     nansi*.asm    - console driver source files
  267.     nansi.sys    - console driver executable file
  268.     nansi.doc    - console driver documentation (this file)
  269.     view.*        - a fast VI-like file viewer, documentation
  270.     more.*        - a fast page-at-a-time TYPE command, documentation
  271.     unsetraw.*    - program to set/unset RAW mode from DOS command line
  272.     mode*.set    - example Set Mode escape sequences
  273.     mode*.rst    - example Reset Mode escape sequences
  274.